feat(mail): drop the Pub/Sub requirement — scheduled fetch as primary intake (HT-94) - #107

…-94)

Second half of dropping the Pub/Sub requirement. The first commit made push
optional; without this one a push-free deployment would ingest mail once a
day, because the reconciliation sweep was welded to the daily
watch-maintenance cron.

The sweep moves to src/mail/gmail-reconcile-sweep.ts and runs every minute
as its own cron. Two reasons it became a separate entry point rather than a
flag on the existing one:

- Cadence. As a push backstop it ran daily; as the primary transport it
  runs every minute. Those cannot share a cron.
- Cost, and this is the load-bearing one. Watch renewal must acquire an
  access token per mailbox because it calls users.watch(). The sweep must
  not — it reads a stored cursor and enqueues, making no Gmail call at all.
  Keeping them welded would have meant a token refresh per mailbox per
  MINUTE against Google's token endpoint, for a call the sweep never makes.
  The reconcile consumer acquires its own token when it actually talks to
  Gmail.

Nothing about reconciliation itself changes: the sweep enqueues the SAME
GMAIL_RECONCILE_TOPIC job the push webhook enqueues, consumed by the same
handler. A deployment without Pub/Sub ingests through exactly the code path
a deployment with it does, triggered by a clock instead of a notification.
That equivalence is what makes this safe under the mail-semantics
invariant.

Enqueues still carry no dedupeKey. At every-minute cadence the consumer's
lease (HT-48) stops being an efficiency guard and becomes structural: ticks
WILL overlap a still-running reconcile on a busy mailbox, and the lease is
what makes that a no-op rather than duplicated fetching.

watch-maintenance is now renewal-only, still daily, and its module doc no
longer describes behavior that moved. The now-dead queue dependency is
removed from its deps rather than left unused.

Runbook: Part A leads with A3/A4 being optional and why skipping them is
recommended — six fewer steps, no billing requirement, and neither of the
two silent-failure traps. The cron list is corrected from a stale "three"
to the actual five, which also closes one of the doc-drift defects found
while mapping the current setup path.

Verified: tsc exit 0, biome exit 0, 1517 tests pass across 76 files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…e (HT-94)

Three independent reviews (two Opus-tier, one Codex) attacked this PR.
Two of the three claims I asked them to scrutinize did not survive.

**Health returned 503 permanently on the install path the runbook now
recommends.** health.ts alerts `watch-expiring` when an active mailbox has
no watch() expiration — which is the DESIGNED steady state once push is
optional. Since the endpoint's contract is a single boolean, that permanent
false alarm made every real alert invisible. runHealthCheck now takes
`pushConfigured` and gates the watch alerts on it. Deliberately a config
fact, not inferred from data: a NULL expiration means "no push configured"
on one deployment and "renewal cron is broken" on another, and only the
config distinguishes them. The gate is scoped to watch alerts —
mailbox-needs-attention still fires either way, with a test proving it.

I verified the column was nullable and stopped there, never checking what
READS it.

**The sweep now enqueues with `dedupeKey: mailboxId`.** Carrying "no
dedupeKey" from a DAILY cadence to an every-minute one was the actual
mistake, and it was not benign:

- The consumer lease does not make contention free. A failed claim returns
  retry, the queue counts attempts, and jobs DEAD-LETTER at the cap. A
  reconcile outrunning the retry window made every tick behind it burn its
  attempts and dead-letter — tripping queue-dead-letter-growth, a second
  permanent 503. The lease prevents duplicated work, not duplicated rows.
- There was no backpressure at all. Enqueue was unconditional per mailbox
  per minute against a bounded drain batch shared with webhook delivery.

The original reasoning ("a quiet mailbox must still be swept") argues
against a COMPOSITE key, not the bare mailboxId: the partial unique index
only suppresses against still-live jobs, so a completed job unblocks the
next tick. Tests now prove that against the REAL Postgres queue over
PGlite, not a fake — a fake cannot exercise the index and would be
tautological. This also aligns the sweep with the push path, which has
always used a dedupe key.

**Coverage for the three headline branches**, all previously untested:
push-free health, resolveGmailPush (all-unset succeeds; every partial
throws naming the missing vars), and the new cron endpoint's routing and
CRON_SECRET enforcement.

**Runbook**: watch-expiring documented as push-only, and its remediation
corrected — a manual GET of watch-maintenance is a no-op on a push-free
deployment, so seeing that alert there is a bug, not a mailbox problem.
Added the two new log events and queue guidance for the push-free case.

**Corrections**: root.ts logged the maintenance skip under a different
event name than the module itself uses; the vestigial queue dependency and
its test helper are removed rather than left unused.

Not fixed, reported instead: my "exactly the same code path" claim was
overstated — push dedupes and (before this change) the sweep did not, and
`job.historyId` carries semantically opposite values depending on trigger.
Harmless while nothing reads it; noted in specs/mail/mailbox-connection.md.

One reviewer claim I overruled: Codex held that revoked OAuth grants would
go undetected without the old per-sweep token probe. listActiveMailboxes
excludes needs_reconnect at the SQL level and the consumer acquires a token
per job, so detection is now FASTER (~1h vs 24h) and a flagged mailbox
drops out of the sweep. What was lost is three counters — observability,
not correctness.

Verified: tsc exit 0, biome exit 0, 1531 tests pass across 76 files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>